BBS in a Box 3/BBS in a box - Trilogy III.iso/Files/Tele/G/Generic Tabby Documentation

Text File | 1989-07-09 | 13.9 KB | 361 lines | [TEXT/QED1]

Tabby Version 2.0 Generic File Format Specification

by Michael E. Connick


Purpose

The purpose of this document is to provide a description of the
new Tabby Version 2.0 Generic Message File Format. It will
also provide a functional description for Import and Export
procedures required in BBS programs to make use of this file
structure.


Introduction

Version 2.0 of Tabby will include a major change in design
philosophy over previous versions of Tabby. Instead of creating
a customized version of Tabby for each BBS to be supported, a
single "generic" version of Tabby will be created.

This will be accomplished having Tabby pick up and deliver
netmail and Echomail messages from "generic" message files.
These generic message files represent a virtual BBS message
structure that Tabby 2.0 will support. Tabby 2.0 will ONLY
support these generic message files. It will no longer directly
support individual BBS message system architectures.

Any BBS that intends to support Tabby will be required to
provide Generic File Import and Export procedures. These
procedures may be standalone programs or integrated routines
within the BBS program. In any case, their function will be to
provide an interface between the native BBS message file
structure and the Tabby Generic Message File structure.

The function of the Import procedure will be to Import netmail
and Echomail messages from the Generic Import File and deliver
them in the proper format to the BBS mail and public message
systems. The Export procedure will perform the opposite
function. It will take newly entered outgoing netmail messages
and messages posted to Echomail message sections of the BBS
and deliver them in the proper format to the Generic Export
file.


Generic File Format

The Tabby Generic file format will actually consist of two
independent files having an indentical structure. These files
are the Generic Import file and the Generic Export file. The
Import file will contain messages which must be imported into
the BBS by the Import procedure. The Export file will contain
outgoing BBS netmail and Echomail messages placed there by
the Export procedure.

Since both the Generic Import and Generic Export files have an
identical format they will be collectively refered to as the
Generic file.

The format of the Generic file has been designed with the goal
of being extremely easy for programmers to deal with it. The
structure of the file is extremely simple and straight
forward. The file format was created in such a manner that
programmers writing the Import and Export procedures could
easily use just about any Mac programming language to access
the file. In addition the design was influenced by the desire
to make the file formats very easy to use when debugging
Import and Export procedures.

The basic philosophy behind the Generic file format is that
each field will always contain printable ASCII characters or a
NULL and will be terminated by a carriage return character.
Following is a more detail description of the format:


Tabby Generic File Record

Record Flags
Category Number
Message Date
Message Time
Originating or Destination Node
From
To
Subject
Text Lines (optional)
NULL Line


Record Flags - 4 bytes (including terminating carriage return)

    Flag Byte 1 -Deletion Flag
        Equal to 'D' if record deleted
    Flag Byte 2 -Record Type
        Equal to 'E' if Echomail
        Equal to 'M' if netmail
    Flag Byte 3 -Reserved for future use
        Ignore
    Flag Byte 4 -Always a carriage return (CR)

Category Number - 4 bytes (including terminating CR)

This field is used only with Echomail, it should be
ignored for netmail. The field contains three ASCII
numeric characters representing the category number
for the Echomail conference this message is associated
with. This category number is the BBS public message
section number that contains messages for this Echomail
conference.  The number corresponds to the Echomail
Area category number specified by the Tabby Maint program
and contained in the "areas.bbs" Tabby file. The field
will always be three digits in length and will have
leading zeroes if the number is less than three digits.

Message Date - 9 bytes (including terminating CR)

This field contains contains an 8 character date.
The format of the date field is as follows:

MM/DD/YY

where MM is a two digit month number, DD a two digit
day of the month, and YY a two digit year. Each of
these will have a leading zero if less than two
digits.

Message Time - 9 bytes (including terminating CR)

This field contains contains an 8 character time.
The format of the time field is as follows:

HH:MM:SS

where HH is a two digit hour (military or 24 hour time)
number, MM a two digit minutes, and SS a two digit
seconds. Each of these will have a leading zero if less
than two digits.

Originating or Destination Node - variable length not to
exceed 16 characters (including terminating CR)

This field contains the originating node number of the
message in the Generic Import file, and the
destination node for the message in the Generic Export
file. This will contain a standard Fidonet compatible
node address, WITHOUT zone. For example our Fidonet
node number would be represented in this field as:

107/512

From - variable length not to exceed 80 bytes (including
terminating CR)

This field contains the name of the person who
composed the message.

To - variable length not to exceed 80 bytes (including
terminating CR)

This field contains the name of the person to whom
the message is addressed.

Subject - variable length not to exceed 80 bytes (including
terminating CR)

This field contains subject of the message.

Text Lines (0 to a maximum of 400) - each line variable
length not to exceed 90 bytes (including terminating CR)

These fields will contain the actual text of the
message. They are optional, i.e., a message can be
sent with only header information and no text
associated with it.

Line containing a NULL - 2 bytes (including terminating CR)

This line will terminate the message and will consist
of a single NULL character (byte containing zero).
This is the ONLY use of the NULL character in the
Generic file. NULL characters must NOT appear in any
of the other fields. They may only contain printable
ASCII characters.


Import Procedure Functional Specification

The Import procedure is responsible for taking netmail and
Echomail messages out of the Generic Import file, reformatting
them, and putting them in the appropriate BBS file.

As each message is processed and delivered to the BBS, the
corresponding Delete flag in the record should be set equal to
a 'D' and the record rewritten into the file. This will
prevent messages from being delivered multiple times into the
BBS. Obviously this also implies that the Import procedure
should ignore any record in the Import file that has a delete
flag equal to 'D'.

The Import procedure should next check the Record Type Flag
field to determine if the message is netmail or Echomail. If
it's a netmail message it can be directly delivered into the
BBS's mail system. If it's an Echomail message, the Category
Number field will need to be checked to determine which public
message section the message should be delivered to.

The processing of the Date, Time, Originating Node, From, and
To fields should be quite simple. Most likely the Message Date
field will require reformatting to be acceptable to the BBS.

The Text Line formatting is probably the most complex function
of the Import program. First of all, remember that a message
may have NO text lines associated with it. This is quite
common for messages which are used to transmit file
attachments and ArcMail.

Next, the Text Line fields will probably require reformatting
to the appropriate line length required by the BBS program.
They are simply guaranteed not to exceed 90 characters in
length. Blank lines between paragraphs will contain only a
carriage return and no other text characters.

The end of the message text is indicated by a NULL line. This
will contain a single NULL followed by the normal carriage
return line terminator.

Upon completing processing of the Generic Import file, the Import
function should delete this file.


Export Procedure Functional Specification

The Export procedure is responsible for finding newly entered
netmail and Echomail messages in the BBS, reformatting them,
and appending them to the Generic Export file. The Generic
Export file should alway be appended to if it exists, or
created if it does not exist.

The Export procedure will need to have a method of determining
which BBS netmail and Echomail messages have been posted since
the last time the Export procedure was executed. Otherwise,
the same messages are going to end up being sent out by Tabby
over and over again. The Export procedure may accomplish this
by saving the date/time of the last time it was run, or by
keeping track of the highest message number last processed.

In addition the Export procedure is going to need to
distinguish between Echomail messages entered by the BBS
users, and those that were delivered by the Import procedure
from Tabby. Only those messages that were entered by the BBS
users can be put into the Generic Export file. Tabby itself
will take care of distributing Echomail messages received to
additional Echomail partner systems. For example if you're
polling System A to pick up an Echo and System B is polling you
to get messages for that Echo, Tabby will take care of making
sure that copies of the Echomail messages picked up from
System A are sent to System B. The Export procedure needs to
ONLY deal with messages entered on the BBS by the users of the
BBS.

The Export procedure will need to set the Record Type Flag
field to indicate whether each message it is placing in the
Generic Export file is netmail or Echomail. If it's a netmail
message the Record Type Flag must be set to a 'M'. If it's an
Echomail message the Record Type Flag must be set to an 'E'.

If the message is an outgoing Echomail message, the Category
Number field should contain the BBS message section number of
the message, properly formatted as a three digit ASCII number
with leading zeroes. If the message is netmail, the Category
Number field should be set to three ASCII '0' digits.

The Destination Node field should only contain a node number
if the message is a netmail message. The Destination Node field
will be ignored for outgoing Echomail messages.

The processing of the Date, Time, From, and To fields should
be quite simple. Most likely the Message Date field will require
reformatting from the native BBS format into the Generic Export
file format.

The Text Line formatting is also quite simple. Remember that
Text Line fields MUST be terminated by a carriage return and
MUST NOT exceed 90 characters in length, INCLUDING the
terminating carriage return. Blank lines between paragraphs
will contain only a single carriage return.

The end of the message text is indicated by a NULL line. This
will contain a single NULL followed by the normal carriage
return line terminator. Be sure to output this NULL line to
the Generic Export file.


Additional BBS Interface Files

Two additional files complete the interface between Tabby and the BBS:
the Generic file, and the Next Event file. Both of theses files will be
found in the same folder as the BBS program and the Tabby programs.

The Generic file will contain an absolute path name of the folder in
which the Generic Import and Generic Export files reside. This path name
will be terminated by a ":" character following by a carriage return.

The Next Event file will contain an 8 character record terminated by
a carriage return. The record consists of ASCII digits representing the
starting and ending time of the next time the Tabby system should be
started up. These times are in "military" or "24 hour" format. For example
if the starting and ending times for the next Tabby Event were 9:00 AM and
1:00 PM, the Next Event record would contain the following:

09001300

When the BBS detects that the current time falls within this time period,
it should terminate the current caller and launch TabbyNet. The TabbyNet
program (and all other Tabby programs) will be located in the same folder
as the BBS, so launching it should be quite easy. The Tabby system will
automatically re-launch the BBS when its Event processing is completed.

The Tabby system is capable of supporting multiple Events in a single day,
so the BBS should check the Next Event file everytime it is launched.


Handling "Crashmail"

The Fidonet network protocol supported by Tabby allows for both scheduled
and unscheduled connection to take place. Unscheduled connections are
usually refered to as Crashmail. For a BBS program to take full advantage
of Tabby, it should be capable of supporting the receipt of Crashmail. To
do this, it needs to be able to differentiate between human and Fidonet
callers. This is accomplished by looking for a TSYNC character in the
normal login input sequence. This character has a hex value of AE. Receipt
of this character should cause the BBS to take the following action:

1. Create a file in the current folder named connect.bbs and containing
a single carriage return terminated record. The first character of this
record should contain an "a" if the BBS modem is attached to the serial
port, and a "b" if the BBS modem is attached to the printer port. The next
characters should contain ASCII digits giving the baud rate of the
connection. For example if the BBS has its modem attached to the serial
port and a 9600 baud connection is made to it that turns out to be a
Fidonet call, the BBS should create a connect.bbs file containing the
following record:

a9600

2. After writing out and closing the connect.bbs file, the BBS program
should launch the TabbyNet program.


Questions?

This concludes the interface requirements of BBS when used with Tabby 2.0.
If you have any questions about the information contained in this
document, feel free to get in contact with me. I can be reached over
Fidonet at 107/412, over Alternet at 520/412, on our BBS at 300/1200/
2400/9600 HST baud at 201-988-0706, or via US Mail at:

ME Connick and Company
PO Box 307
Bradley Beach, NJ 07720